home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-35
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-05-11
|
50KB
|
770 lines
This is Info file elisp, produced by Makeinfo-1.52 from the input file
elisp.texi.
This file documents GNU Emacs Lisp.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Including Diary Files, Up: Calendar
Sexp Entries and the Fancy Diary Display
========================================
Sexp diary entries allow you to
do more than just have complicated conditions under which a diary entry
applies. If you use the fancy diary display, sexp entries can generate
the text of the entry depending on the date itself. For example, the
anniversary diary entry described above (*note Special Diary
Entries::.) can insert the number of years since the anniversary date
into the text of the diary entry. Thus the `%d' in the dairy entry
%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old)
gets replaced by the age, so on
October 31, 1990 the entry appears in the fancy diary buffer as
Arthur's birthday (42 years old)
If the diary file instead contains
the entry
%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday
the entry in the fancy diary buffer
for October 31, 1990 becomes
Arthur's 42nd birthday
Similarly, cyclic diary entries
can interpolate the number of repetitions that have occurred:
%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time)
causes the diary entry
Renew medication (5th time)
to appear in the fancy diary display
on September 8, 1990.
The generality of sexp diary
entries lets you specify any diary entry that you can describe
algorithmically. Suppose you get paid on the 21st of the month if it
is a weekday, and to the Friday before if the 21st is on a weekend.
The diary entry
&%%(let ((dayname (calendar-day-of-week date))
(day (car (cdr date))))
(or (and (= day 21) (memq dayname '(1 2 3 4 5)))
(and (memq day '(19 20)) (= dayname 5)))
) Pay check deposited
applies to just those dates. This
example illustrates how the sexp can depend on the variable `date';
this variable is a list (MONTH DAY YEAR) that gives the Gregorian date
for which the diary entries are being found. If the value of the
expression is `t', the entry applies to that date. If the expression
evaluates to `nil', the entry does *not* apply to that date.
The following sexp diary entries
take advantage of the ability (in the fancy diary display) to concoct
diary entries based on the date:
`%%(diary-sunrise-sunset)'
Make a diary entry for the
local times of today's sunrise
and sunset.
`%%(diary-phases-of-moon)'
Make a diary entry for the
phases (quarters) of the moon.
`%%(diary-day-of-year)'
Make a diary entry with today's
day number in the current year
and the number of days
remaining in the current year.
`%%(diary-iso-date)'
Make a diary entry with today's
equivalent ISO commercial date.
`%%(diary-julian-date)'
Make a diary entry with today's
equivalent date on the Julian
calendar.
`%%(diary-astro-day-number)'
Make a diary entry with today's
equivalent astronomical
(Julian) day number.
`%%(diary-hebrew-date)'
Make a diary entry with today's
equivalent date on the Hebrew
calendar.
`%%(diary-islamic-date)'
Make a diary entry with today's
equivalent date on the Islamic
calendar.
`%%(diary-french-date)'
Make a diary entry with today's
equivalent date on the French
Revolutionary calendar.
`%%(diary-mayan-date)'
Make a diary entry with today's
equivalent date on the Mayan
calendar.
Thus including the diary entry
&%%(diary-hebrew-date)
causes every day's diary display to
contain the equivalent date on the Hebrew calendar, if you are using
the fancy diary display. (With simple diary display, the line
`&%%(diary-hebrew-date)' appears in the diary for any date, but does
nothing particularly useful.)
There are a number of other
available sexp diary entries that are important to those who follow the
Hebrew calendar:
`%%(diary-rosh-hodesh)'
Make a diary entry that tells
the occurrence and ritual
announcement of each new Hebrew
month.
`%%(diary-parasha)'
Make a Saturday diary entry
that tells the weekly synagogue
scripture reading.
`%%(diary-sabbath-candles)'
Make a Friday diary entry that
tells the *local time* of
Sabbath candle lighting.
`%%(diary-omer)'
Make a diary entry that gives
the omer count, when
appropriate.
`%%(diary-yahrzeit MONTH DAY YEAR) NAME'
Make a diary entry marking the
anniversary of a date of death.
The date is the *Gregorian*
(civil) date of death. The
diary entry appears on the
proper Hebrew calendar
anniversary and on the day
before. (In the European
style, the order of the
parameters is changed to DAY,
MONTH, YEAR.)
File: elisp, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar
Customizing Appointment Reminders
=================================
You can specify exactly how Emacs
reminds you of an appointment and how far in advance it begins doing
so. Here are the variables that you can set:
`appt-message-warning-time'
The time in minutes before an
appointment that the reminder
begins. The default is 10
minutes.
`appt-audible'
If this is `t' (the default),
Emacs rings the terminal bell
for appointment reminders.
`appt-visible'
If this is `t' (the default),
Emacs displays the appointment
message in echo area.
`appt-display-mode-line'
If this is `t' (the default),
Emacs displays the number of
minutes to the appointment on
the mode line.
`appt-msg-window'
If this is `t' (the default),
Emacs displays the appointment
message in another window.
`appt-display-duration'
The number of seconds an
appointment message is
displayed. The default is 5
seconds.
File: elisp, Node: Tips, Next: GNU Emacs Internals, Prev: Calendar, Up: Top
Tips and Standards
******************
This chapter describes no
additional features of Emacs Lisp. Instead it gives advice on making
effective use of the features described in the previous chapters.
* Menu:
* Style Tips:: Writing clean and robust programs.
* Compilation Tips:: Making compiled code run fast.
* Documentation Tips:: Writing readable documentation strings.
* Comment Tips:: Conventions for writing comments.
* Library headers:: Standard headers for library packages.
File: elisp, Node: Style Tips, Next: Compilation Tips, Prev: Tips, Up: Tips
Writing Clean Lisp Programs
===========================
Here are some tips for avoiding
common errors in writing Lisp code intended for widespread use:
* Since all global variables
share the same name space, and
all functions share another
name space, you should choose a
short word to distinguish your
program from other Lisp
programs. Then take care to
begin the names of all global
variables, constants, and
functions with the chosen
prefix. This helps avoid name
conflicts.
This recommendation applies
even to names for traditional
Lisp primitives that are not
primitives in Emacs Lisp--even
to `cadr'. Believe it or not,
there is more than one
plausible way to define `cadr'.
Play it safe; append your name
prefix to produce a name like
`foo-cadr' or `mylib-cadr'
instead.
If one prefix is insufficient,
your package may use two or
three alternative common
prefixes, so long as they make
sense.
Separate the prefix from the
rest of the symbol name with a
hyphen, `-'. This will be
consistent with Emacs itself
and with most Emacs Lisp
programs.
* It is often useful to put a
call to `provide' in each
separate library program, at
least if there is more than one
entry point to the program.
* If one file FOO uses a macro
defined in another file BAR,
FOO should contain `(require
'BAR)' before the first use of
the macro. (And BAR should
contain `(provide 'BAR)', to
make the `require' work.) This
will cause BAR to be loaded
when you byte-compile FOO.
Otherwise, you risk compiling
FOO without the necessary macro
loaded, and that would produce
compiled code that won't work
right. *Note Compiling
Macros::.
* If you define a major mode,
make sure to run a hook
variable using `run-hooks',
just as the existing major
modes do. *Note Hooks::.
* Please do not define `C-c
LETTER' as a key in your major
modes. These sequences are
reserved for users; they are the
*only* sequences reserved for
users, so we cannot do without
them.
Instead, define sequences
consisting of `C-c' followed by
a non-letter. These sequences
are reserved for major modes.
Changing all the major modes in
Emacs 18 so they would follow
this convention was a lot of
work. Abandoning this
convention would waste that
work and inconvenience the
users.
* It is a bad idea to define
aliases for the Emacs
primitives. Use the standard
names instead.
* Redefining an Emacs primitive
is an even worse idea. It may
do the right thing for a
particular program, but there
is no telling what other
programs might break as a
result.
* If a file does replace any of
the functions or library
programs of standard Emacs,
prominent comments at the
beginning of the file should
say which functions are
replaced, and how the behavior
of the replacements differs
from that of the originals.
* If a file requires certain
standard library programs to be
loaded beforehand, then the
comments at the beginning of
the file should say so.
* Please keep the names of your
Emacs Lisp source files to 13
characters or less. This way,
if the files are compiled, the
compiled files' names will be
14 characters or less, which is
short enough to fit on all kinds
of Unix systems.
* Don't use `next-line' or
`previous-line' in programs;
nearly always, `forward-line'
is more convenient as well as
more predictable and robust.
*Note Text Lines::.
* Don't use functions that set
the mark in your Lisp code
(unless you are writing a
command to set the mark). The
mark is a user-level feature,
so it is incorrect to change
the mark except to supply a
value for the user's benefit.
*Note The Mark::.
In particular, don't use these
functions:
* `beginning-of-buffer',
`end-of-buffer'
* `replace-string',
`replace-regexp'
If you just want to move point,
or replace a certain string,
without any of the other
features intended for
interactive users, you can
replace these functions with
one or two lines of simple Lisp
code.
* The recommended way to print a
message in the echo area is with
the `message' function, not
`princ'. *Note The Echo Area::.
* When you encounter an error
condition, call the function
`error' (or `signal'). The
function `error' does not
return. *Note Signaling
Errors::.
Do not use `message', `throw',
`sleep-for', or `beep' to
report errors.
* Avoid using recursive edits.
Instead, do what the Rmail `w'
command does: use a new local
keymap that contains one
command defined to switch back
to the old local keymap. Or do
what the `edit-options' command
does: switch to another buffer
and let the user switch back at
will. *Note Recursive
Editing::.
* In some other systems there is
a convention of choosing
variable names that begin and
end with `*'. We don't use
that convention in Emacs Lisp,
so please don't use it in your
library. (In fact, in Emacs
names of this form are
conventionally used for
program-generated buffers.) The
users will find Emacs more
coherent if all libraries use
the same conventions.
* Indent each function with
`C-M-q' (`indent-sexp') using
the default indentation
parameters.
* Don't make a habit of putting
close-parentheses on lines by
themselves; Lisp programmers
find this disconcerting. Once
in a while, when there is a
sequence of many consecutive
close-parentheses, it may make
sense to split them in one or
two significant places.
* Please put a copyright notice
on the file if you give copies
to anyone. Use the same lines
that appear at the top of the
Lisp files in Emacs itself. If
you have not signed papers to
assign the copyright to the
Foundation, then place your
name in the copyright notice in
place of the Foundation's name.
File: elisp, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips
Tips for Making Compiled Code Fast
==================================
Here are ways of improving the
execution speed of byte-compiled lisp programs.
* Use the `profile' library to
profile your program. See the
file `profile.el' for
instructions.
* Use iteration rather than
recursion whenever possible.
Function calls are slow in
Emacs Lisp even when a compiled
function is calling another
compiled function.
* Using the primitive
list-searching functions
`memq', `assq' or `assoc' is
even faster than explicit
iteration. It may be worth
rearranging a data structure so
that one of these primitive
search functions can be used.
* Certain built-in functions are
handled specially by the byte
compiler avoiding the need for
an ordinary function call. It
is a good idea to use these
functions rather than
alternatives. To see whether a
function is handled specially
by the compiler, examine its
`byte-compile' property. If
the property is non-`nil', then
the function is handled
specially.
For example, the following
input will show you that `aref'
is compiled specially (*note
Array Functions::.) while `elt'
is not (*note Sequence
Functions::.):
(get 'aref 'byte-compile)
=> byte-compile-two-args
(get 'elt 'byte-compile)
=> nil
* Make small functions inline, so
that calls to them in compiled
code run faster. *Note Inline
Functions::.
File: elisp, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips
Tips for Documentation Strings
==============================
Here are some tips for the
writing of documentation strings.
* Every command, function or
variable intended for users to
know about should have a
documentation string.
* An internal subroutine of a
Lisp program need not have a
documentation string, and you
can save space by using a
comment instead.
* The first line of the
documentation string should
consist of one or two complete
sentences which stand on their
own as a summary. In
particular, start the line with
a capital letter and end with a
period.
The documentation string can
have additional lines which
expand on the details of how to
use the function or variable.
The additional lines should be
made up of complete sentences
also, but they may be filled if
that looks good.
* Do not start or end a
documentation string with
whitespace.
* Format the documentation string
so that it fits in an Emacs
window on an 80 column screen.
It is a good idea for most
lines to be no wider than 60
characters. The first line can
be wider if necessary to fit the
information that ought to be
there.
However, rather than simply
filling the entire
documentation string, you can
make it much more readable by
choosing line breaks with care.
Use blank lines between topics
if the documentation string is
long.
* *Do not* indent subsequent
lines of a documentation string
so that the text is lined up in
the source code with the text
of the first line. This looks
nice in the source code, but
looks bizarre when users view
the documentation. Remember
that the indentation before the
starting double-quote is not
part of the string!
* A variable's documentation
string should start with `*' if
the variable is one that users
would want to set interactively
often. If the value is a long
list, or a function, or if the
variable would only be set in
init files, then don't start
the documentation string with
`*'. *Note Defining
Variables::.
* The documentation string for a
variable that is a yes-or-no
flag should start with words
such as "Non-nil means...", to
make it clear both that the
variable only has two
meaningfully distinct values
and which value means "yes".
* When a function's documentation
string mentions the value of an
argument of the function, use
the argument name in capital
letters as if it were a name
for that value. Thus, the
documentation string of the
function `/' refers to its
second argument as `DIVISOR'.
Also use all caps for
meta-syntactic variables, such
as when you show the
decomposition of a list or
vector into subunits, some of
which may be variable.
* When a documentation string
refers to a Lisp symbol, write
it as it would be printed
(which usually means in lower
case), with single-quotes
around it. For example:
``lambda''. There are two
exceptions: write `t' and `nil'
without single-quotes.
* Don't write key sequences
directly in documentation
strings. Instead, use the
`\\[...]' construct to stand
for them. For example, instead
of writing `C-f', write
`\\[forward-char]'. When the
documentation string is
printed, Emacs will substitute
whatever key is currently bound
to `forward-char'. This will
usually be `C-f', but if the
user has moved key bindings, it
will be the correct key for
that user. *Note Keys in
Documentation::.
* In documentation strings for a
major mode, you will want to
refer to the key bindings of
that mode's local map, rather
than global ones. Therefore,
use the construct `\\<...>'
once in the documentation
string to specify which key map
to use. Do this before the
first use of `\\[...]'. The
text inside the `\\<...>'
should be the name of the
variable containing the local
keymap for the major mode.
It is not practical to use
`\\[...]' very many times,
because display of the
documentation string will
become slow. So use this to
describe the most important
commands in your major mode,
and then use `\\{...}' to
display the rest of the mode's
keymap.
* Don't use the term "Elisp",
since that is or was a
trademark. Use the term "Emacs
Lisp".
File: elisp, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips
Tips on Writing Comments
========================
We recommend these conventions
for where to put comments and how to indent them:
`;'
Comments that start with a
single semicolon, `;', should
all be aligned to the same
column on the right of the
source code. Such comments
usually explain how the code on
the same line does its job. In
Lisp mode and related modes,
the `M-;' (`indent-for-comment')
command automatically inserts
such a `;' in the right place,
or aligns such a comment if it
is already inserted.
(The following examples are
taken from the Emacs sources.)
(setq base-version-list ; there was a base
(assoc (substring fn 0 start-vn) ; version to which
file-version-assoc-list)) ; this looks like
; a subversion
`;;'
Comments that start with two
semicolons, `;;', should be
aligned to the same level of
indentation as the code. Such
comments are used to describe
the purpose of the following
lines or the state of the
program at that point. For
example:
(prog1 (setq auto-fill-function
...
...
;; update mode-line
(force-mode-line-update)))
These comments are also written
before a function definition to
explain what the function does
and how to call it properly.
`;;;'
Comments that start with three
semicolons, `;;;', should start
at the left margin. Such
comments are not used within
function definitions, but are
used to make more general
comments. For example:
;;; This Lisp code is run in Emacs
;;; when it is to operate asa server
;;; for other processes.
`;;;;'
Comments that start with four
semicolons, `;;;;', should be
aligned to the left margin and
are used for headings of major
sections of a program. For
example:
;;;; The kill ring
The indentation commands of the Lisp
modes in Emacs, such as `M-;' (`indent-for-comment') and TAB
(`lisp-indent-line') automatically indent comments according to these
conventions, depending on the the number of semicolons. *Note
Manipulating Comments: (emacs)Comments.
If you wish to "comment out" a
number of lines of code, use triple semicolons at the beginnings of the
lines.
Any character may be included in
a comment, but it is advisable to precede a character with syntactic
significance in Lisp (such as `\' or unpaired `(' or `)') with a `\',
to prevent it from confusing the Emacs commands for editing Lisp.
File: elisp, Node: Library Headers, Prev: Comment Tips, Up: Tips
Conventional Headers for Emacs Library Packages
===============================================
There are some standard
identication headers used in Emacs 19 library packages to assist the
help system, track authors and versions for maintainence purposes, and
enable the generation of various kinds of databases and documentation.
This section explains them and
why you should try to use the same conventions in your packages,
especially if you want to submit them to FSF.
Here's the head of a file written
using the library conventions:
;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
;; Copyright (C) 1992 Free Software Foundation, Inc.
;; Author: Eric S. Raymond <esr
;; Maintainer: Eric S. Raymond <esr
;; Created: 14 Jul 1992
;; Version: 1.2
;; Keywords: docs
;; Bogus-Bureaucratic-Cruft: Gruad will get you if you don't watch out!
;; This file is part of GNU Emacs.
Here are the new features:
*Header line* -- makes it
possible to extract a one-line summary of the package's uses
automatically for use in library synopses, KWIC indexes and the like.
Format is three semicolons,
followed by the filename, followed by three dashes, followed by the
summary. All fields space-separated.
*Author line* -- contains the
name and net address of at least the principal author.
If there are multiple authors,
they should be listed on continuation lines led by `;;<TAB>', like this:
;; Author: Ashwin Ram <Ram-Ashwin
;; Dave Sill <de5
;; David Lawrence <tale
;; Noah Friedman <friedman
;; Joe Wells <jbw
;; Dave Brennan <brennan
;; Eric Raymond <esr
This field may have some special
values; notably "FSF", meaning "Free Software Foundation".
*Maintainer line* -- should be a
single name/address as in the Author line, or an address only, or the
string "FSF". If there is no maintainer line, the person(s) in the
Author field are presumed to be it. The example in this file is mildly
bogus because the maintainer line is redundant.
The idea behind these two fields
is to be able to write a lisp function that does "send mail to the
author" without having to mine the name out by hand. Please be careful
about surrounding the network address with <> if there's also a name in
the field.
*Created line* -- optional, gives
the original creation date of the file. For historical interest,
basically.
*Version line* -- intended to
give the reader a clue if they're looking at a different version of the
file than the one they're accustomed to. Not needed if you have an RCS
or SCCS header.
*Adapted-By line* -- this is for
FSF's internal use. The person named in this field was the one
responsible for installing and adapting the package for the
distribution. (This file doesn't have one because the author *is* one
of the maintainers.)
*Keywords line* -- used by the
package-finder code for finding elisp code related to a topic. This
field is important; it's how people will find your package when they're
looking forthings by topic area.
*Bogus-Bureaucratic-Cruft line*
-- this is a joke. We figured we should satirize this design before
someone else did. Also, it illustrates the possibility that other
headers may be added in the future for new purposes.
There are a few other stylized
comments all the distribution files comtain. These are:
*Commentary line* -- optional,
enables lisp code to find the developer's and maintainers' explanations
of the package internals. It looks like this:
smallexample ;;; Commentary:
smallexample
and should be located after the
GNU copyright but before the package's header comments (if any).
*Change log line* -- optional,
exists to terminate the commentary section and start a change-log part,
if one exists. It looks like this:
smallexample ;;; Change Log:
smallexample
*Code line* -- exists so lisp can
know where the commentary and/or change-log sections end. It looks
like this:
smallexample ;;; Code:
smallexample
*Footer line* -- marks
end-of-file so it can be distinguished from an expanded formfeed or the
results of truncation. This must be the *last* line in the file.
Example:
smallexample ;;; lisp-mnt.el ends
here smallexample
The mode used as an example
actually exists and can actually be used to generate these headers
semi-automatically. It provides functions which lisp programs can use
to etract various useful pieces of information from these headers.